@hypothesi/tauri-mcp-server 0.1.1

package/LICENSE

@@ -0,0 +1,39 @@
+MIT License
+
+Copyright (c) 2025 Fireside Development, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Apache License, Version 2.0
+
+Copyright (c) 2025 Fireside Development, LLC
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/dist/config.js

@@ -0,0 +1,45 @@
+/**
+ * Configuration for the MCP Bridge connection.
+ *
+ * This module provides configuration options for connecting to Tauri apps,
+ * with support for environment variables and sensible defaults.
+ */
+/**
+ * Gets the default host for MCP Bridge connections.
+ *
+ * Resolution priority:
+ * 1. MCP_BRIDGE_HOST environment variable
+ * 2. TAURI_DEV_HOST environment variable (set by Tauri CLI for mobile dev)
+ * 3. 'localhost' (default)
+ */
+export function getDefaultHost() {
+    // eslint-disable-next-line no-process-env
+    return process.env.MCP_BRIDGE_HOST || process.env.TAURI_DEV_HOST || 'localhost';
+}
+/**
+ * Gets the default port for MCP Bridge connections.
+ *
+ * Resolution priority:
+ * 1. MCP_BRIDGE_PORT environment variable
+ * 2. 9223 (default)
+ */
+export function getDefaultPort() {
+    // eslint-disable-next-line no-process-env
+    const port = process.env.MCP_BRIDGE_PORT;
+    return port ? parseInt(port, 10) : 9223;
+}
+/**
+ * Gets the full bridge configuration from environment variables.
+ */
+export function getConfig() {
+    return {
+        host: getDefaultHost(),
+        port: getDefaultPort(),
+    };
+}
+/**
+ * Builds a WebSocket URL from host and port.
+ */
+export function buildWebSocketURL(host, port) {
+    return `ws://${host}:${port}`;
+}

package/dist/driver/app-discovery.js

@@ -0,0 +1,148 @@
+/**
+ * App discovery and session management for multiple Tauri instances.
+ *
+ * This module handles discovering and connecting to multiple Tauri apps
+ * running with MCP Bridge on the same machine or remote devices using port scanning.
+ */
+import { getDefaultHost, getDefaultPort } from '../config.js';
+import { PluginClient } from './plugin-client.js';
+/**
+ * Manages discovery and connection to multiple Tauri app instances
+ */
+export class AppDiscovery {
+    _activeSessions = new Map();
+    _host;
+    _basePort;
+    _maxPorts = 100;
+    constructor(host, basePort) {
+        this._host = host ?? getDefaultHost();
+        this._basePort = basePort ?? getDefaultPort();
+    }
+    /**
+     * Gets the configured host.
+     */
+    get host() {
+        return this._host;
+    }
+    /**
+     * Sets the host for discovery.
+     */
+    setHost(host) {
+        this._host = host;
+    }
+    /**
+     * Discovers available Tauri app instances by scanning ports
+     */
+    async discoverApps() {
+        const apps = [];
+        // Scan port range for available apps
+        for (let offset = 0; offset < this._maxPorts; offset++) {
+            const port = this._basePort + offset;
+            if (await this._isPortInUse(port)) {
+                apps.push({ host: this._host, port, available: true });
+            }
+        }
+        return apps;
+    }
+    /**
+     * Connects to a specific app on a host and port
+     */
+    async connectToPort(port, appName, host) {
+        const targetHost = host ?? this._host;
+        const sessionId = `${targetHost}_${port}`;
+        // Check if already connected
+        const existing = this._activeSessions.get(sessionId);
+        if (existing?.connected) {
+            return existing;
+        }
+        const client = new PluginClient(targetHost, port);
+        try {
+            await client.connect();
+            const session = {
+                appId: sessionId,
+                name: appName || `Tauri App (${targetHost}:${port})`,
+                host: targetHost,
+                port,
+                client,
+                connected: true,
+            };
+            this._activeSessions.set(sessionId, session);
+            return session;
+        }
+        catch (error) {
+            throw new Error(`Failed to connect to ${targetHost}:${port}: ${error}`);
+        }
+    }
+    /**
+     * Gets the first available app
+     */
+    async getFirstAvailableApp() {
+        const apps = await this.discoverApps();
+        return apps.length > 0 ? apps[0] : null;
+    }
+    /**
+     * Disconnects from a specific session
+     */
+    async disconnectSession(sessionId) {
+        const session = this._activeSessions.get(sessionId);
+        if (session?.client) {
+            await session.client.disconnect();
+            this._activeSessions.delete(sessionId);
+        }
+    }
+    /**
+     * Disconnects from all apps
+     */
+    async disconnectAll() {
+        for (const [, session] of this._activeSessions) {
+            if (session.client) {
+                await session.client.disconnect();
+            }
+        }
+        this._activeSessions.clear();
+    }
+    /**
+     * Gets the active session by ID
+     */
+    getSession(sessionId) {
+        return this._activeSessions.get(sessionId);
+    }
+    /**
+     * Gets all active sessions
+     */
+    getAllSessions() {
+        return Array.from(this._activeSessions.values());
+    }
+    /**
+     * Try to connect to the default port
+     */
+    async connectToDefaultPort() {
+        return this.connectToPort(this._basePort, 'Default Tauri App');
+    }
+    /**
+     * Check if a port is in use (likely a Tauri app)
+     */
+    async _isPortInUse(port) {
+        const client = new PluginClient(this._host, port);
+        try {
+            // Try to connect briefly to see if port responds
+            await Promise.race([
+                client.connect(),
+                new Promise((_, reject) => {
+                    setTimeout(() => { reject(new Error('Timeout')); }, 100);
+                }),
+            ]);
+            // Connection succeeded - clean up and return true
+            client.disconnect();
+            return true;
+        }
+        catch {
+            // Connection failed or timed out - always clean up the client
+            // This prevents orphaned WebSocket connections from emitting errors later
+            client.disconnect();
+            return false;
+        }
+    }
+}
+// Singleton instance
+export const appDiscovery = new AppDiscovery();

package/dist/driver/plugin-client.js

@@ -0,0 +1,208 @@
+import WebSocket from 'ws';
+import { EventEmitter } from 'events';
+import { buildWebSocketURL, getDefaultHost, getDefaultPort } from '../config.js';
+/**
+ * Client to communicate with the MCP Bridge plugin's WebSocket server
+ */
+/* eslint-disable no-plusplus */
+export class PluginClient extends EventEmitter {
+    _ws = null;
+    _url;
+    _host;
+    _port;
+    _reconnectAttempts = 0;
+    _shouldReconnect = true; // Keep trying forever until explicitly disconnected
+    _reconnectDelay = 1000; // Start with 1s, max 30s
+    _pendingRequests = new Map();
+    /**
+     * Constructor for PluginClient
+     * @param host Host address of the WebSocket server
+     * @param port Port number of the WebSocket server
+     */
+    constructor(host, port) {
+        super();
+        this._host = host;
+        this._port = port;
+        this._url = buildWebSocketURL(host, port);
+        // CRITICAL: Attach a default error handler to prevent crashes.
+        // In Node.js, if an EventEmitter emits 'error' with no listeners, it throws
+        // an uncaught exception that crashes the process. This is especially important
+        // during port scanning where connections may fail after the caller has moved on.
+        this.on('error', () => {
+            // Silently ignore - errors are also returned via promise rejections
+        });
+    }
+    /**
+     * Creates a PluginClient with default configuration from environment.
+     */
+    static create_default() {
+        return new PluginClient(getDefaultHost(), getDefaultPort());
+    }
+    /**
+     * Gets the host this client is configured to connect to.
+     */
+    get host() {
+        return this._host;
+    }
+    /**
+     * Gets the port this client is configured to connect to.
+     */
+    get port() {
+        return this._port;
+    }
+    /**
+     * Connect to the plugin's WebSocket server
+     */
+    async connect() {
+        return new Promise((resolve, reject) => {
+            if (this._ws?.readyState === WebSocket.OPEN) {
+                resolve();
+                return;
+            }
+            this._ws = new WebSocket(this._url);
+            this._ws.on('open', () => {
+                // Connected to MCP Bridge plugin
+                this._reconnectAttempts = 0;
+                this.emit('connected');
+                resolve();
+            });
+            this._ws.on('message', (data) => {
+                try {
+                    const message = JSON.parse(data.toString());
+                    // Check if this is a response to a pending request
+                    if (message.id && this._pendingRequests.has(message.id)) {
+                        const pending = this._pendingRequests.get(message.id);
+                        if (pending) {
+                            clearTimeout(pending.timeout);
+                            this._pendingRequests.delete(message.id);
+                            pending.resolve(message);
+                        }
+                    }
+                    else {
+                        // It's a broadcast event
+                        this.emit('event', message);
+                    }
+                }
+                catch (e) {
+                    // Failed to parse WebSocket message
+                }
+            });
+            this._ws.on('error', (err) => {
+                // WebSocket error - emit for any listeners, then reject the promise.
+                // Note: The constructor attaches a default error handler to prevent crashes.
+                this.emit('error', err);
+                reject(err);
+            });
+            this._ws.on('close', () => {
+                // Disconnected from MCP Bridge plugin
+                this.emit('disconnected');
+                this._ws = null;
+                // Reject all pending requests since the connection is gone
+                for (const [id, pending] of this._pendingRequests) {
+                    clearTimeout(pending.timeout);
+                    pending.reject(new Error('Connection closed'));
+                    this._pendingRequests.delete(id);
+                }
+                // Auto-reconnect with exponential backoff (max 30s)
+                if (this._shouldReconnect) {
+                    this._reconnectAttempts++;
+                    const delay = Math.min(this._reconnectDelay * this._reconnectAttempts, 30000);
+                    setTimeout(() => {
+                        this.connect().catch(() => {
+                            // Reconnection failed - will retry on next close event
+                        });
+                    }, delay);
+                }
+            });
+        });
+    }
+    /**
+     * Disconnect from the plugin
+     */
+    disconnect() {
+        this._shouldReconnect = false; // Prevent auto-reconnect
+        if (this._ws) {
+            this._ws.close();
+            this._ws = null;
+        }
+    }
+    /**
+     * Send a command to the plugin and wait for response
+     */
+    async sendCommand(command, timeoutMs = 5000) {
+        // If not connected, try to reconnect first
+        if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
+            try {
+                await this.connect();
+            }
+            catch {
+                throw new Error('Not connected to plugin and reconnection failed');
+            }
+        }
+        // Double-check connection after reconnect attempt
+        if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
+            throw new Error('Not connected to plugin');
+        }
+        // Generate unique ID for this request
+        const id = `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        const commandWithId = { ...command, id };
+        return new Promise((resolve, reject) => {
+            // Set up timeout
+            const timeout = setTimeout(() => {
+                this._pendingRequests.delete(id);
+                reject(new Error(`Request timeout after ${timeoutMs}ms`));
+            }, timeoutMs);
+            // Store pending request
+            this._pendingRequests.set(id, { resolve, reject, timeout });
+            // Send command
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            this._ws.send(JSON.stringify(commandWithId), (error) => {
+                if (error) {
+                    clearTimeout(timeout);
+                    this._pendingRequests.delete(id);
+                    reject(error);
+                }
+            });
+        });
+    }
+    /**
+     * Check if connected
+     */
+    isConnected() {
+        return this._ws?.readyState === WebSocket.OPEN;
+    }
+}
+// Singleton instance
+let pluginClient = null;
+/**
+ * Gets or creates a singleton PluginClient.
+ * @param host Optional host override
+ * @param port Optional port override
+ */
+export function getPluginClient(host, port) {
+    const resolvedHost = host ?? getDefaultHost();
+    const resolvedPort = port ?? getDefaultPort();
+    if (!pluginClient) {
+        pluginClient = new PluginClient(resolvedHost, resolvedPort);
+    }
+    return pluginClient;
+}
+/**
+ * Resets the singleton client (useful for reconnecting with different config).
+ */
+export function resetPluginClient() {
+    if (pluginClient) {
+        pluginClient.disconnect();
+        pluginClient = null;
+    }
+}
+export async function connectPlugin(host, port) {
+    const client = getPluginClient(host, port);
+    if (!client.isConnected()) {
+        await client.connect();
+    }
+}
+export async function disconnectPlugin() {
+    const client = getPluginClient();
+    client.disconnect();
+}

package/dist/driver/plugin-commands.js

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+import { getPluginClient, connectPlugin } from './plugin-client.js';
+export const ExecuteIPCCommandSchema = z.object({
+    command: z.string(),
+    args: z.unknown().optional(),
+});
+export async function executeIPCCommand(command, args = {}) {
+    try {
+        // Ensure we're connected to the plugin
+        await connectPlugin();
+        const client = getPluginClient();
+        // Send IPC command via WebSocket to the mcp-bridge plugin
+        const response = await client.sendCommand({
+            command: 'invoke_tauri',
+            args: { command, args },
+        });
+        if (!response.success) {
+            return JSON.stringify({ success: false, error: response.error || 'Unknown error' });
+        }
+        return JSON.stringify({ success: true, result: response.data });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return JSON.stringify({ success: false, error: message });
+    }
+}
+export const GetWindowInfoSchema = z.object({});
+export async function getWindowInfo() {
+    try {
+        const result = await executeIPCCommand('plugin:mcp-bridge|get_window_info');
+        const parsed = JSON.parse(result);
+        if (!parsed.success) {
+            throw new Error(parsed.error || 'Unknown error');
+        }
+        return JSON.stringify(parsed.result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to get window info: ${message}`);
+    }
+}
+// Combined schema for managing IPC monitoring
+export const ManageIPCMonitoringSchema = z.object({
+    action: z.enum(['start', 'stop']).describe('Action to perform: start or stop IPC monitoring'),
+});
+// Keep individual schemas for backward compatibility if needed
+export const StartIPCMonitoringSchema = z.object({});
+export const StopIPCMonitoringSchema = z.object({});
+export async function manageIPCMonitoring(action) {
+    if (action === 'start') {
+        return startIPCMonitoring();
+    }
+    return stopIPCMonitoring();
+}
+export async function startIPCMonitoring() {
+    try {
+        const result = await executeIPCCommand('plugin:mcp-bridge|start_ipc_monitor');
+        const parsed = JSON.parse(result);
+        if (!parsed.success) {
+            throw new Error(parsed.error || 'Unknown error');
+        }
+        return JSON.stringify(parsed.result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to start IPC monitoring: ${message}`);
+    }
+}
+export async function stopIPCMonitoring() {
+    try {
+        const result = await executeIPCCommand('plugin:mcp-bridge|stop_ipc_monitor');
+        const parsed = JSON.parse(result);
+        if (!parsed.success) {
+            throw new Error(parsed.error || 'Unknown error');
+        }
+        return JSON.stringify(parsed.result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to stop IPC monitoring: ${message}`);
+    }
+}
+export const GetIPCEventsSchema = z.object({
+    filter: z.string().optional().describe('Filter events by command name'),
+});
+export async function getIPCEvents(filter) {
+    try {
+        const result = await executeIPCCommand('plugin:mcp-bridge|get_ipc_events');
+        const parsed = JSON.parse(result);
+        if (!parsed.success) {
+            throw new Error(parsed.error || 'Unknown error');
+        }
+        let events = parsed.result;
+        if (filter && Array.isArray(events)) {
+            events = events.filter((e) => {
+                const event = e;
+                return event.command && event.command.includes(filter);
+            });
+        }
+        return JSON.stringify(events);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to get IPC events: ${message}`);
+    }
+}
+export const EmitTestEventSchema = z.object({
+    eventName: z.string(),
+    payload: z.unknown(),
+});
+export async function emitTestEvent(eventName, payload) {
+    try {
+        const result = await executeIPCCommand('plugin:mcp-bridge|emit_event', {
+            eventName,
+            payload,
+        });
+        const parsed = JSON.parse(result);
+        if (!parsed.success) {
+            throw new Error(parsed.error || 'Unknown error');
+        }
+        return JSON.stringify(parsed.result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to emit event: ${message}`);
+    }
+}
+export const GetBackendStateSchema = z.object({});
+export async function getBackendState() {
+    try {
+        const result = await executeIPCCommand('plugin:mcp-bridge|get_backend_state');
+        const parsed = JSON.parse(result);
+        if (!parsed.success) {
+            throw new Error(parsed.error || 'Unknown error');
+        }
+        return JSON.stringify(parsed.result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to get backend state: ${message}`);
+    }
+}

package/dist/driver/protocol.js

@@ -0,0 +1,7 @@
+/**
+ * WebSocket protocol types for communication between MCP server and Tauri plugin
+ *
+ * This file defines the message format for the WebSocket-based communication
+ * between the Node.js MCP server and the Rust Tauri plugin.
+ */
+export {};

package/dist/driver/scripts/find-element.js

@@ -0,0 +1,48 @@
+/**
+ * Find an element using various selector strategies
+ *
+ * @param {Object} params
+ * @param {string} params.selector - Element selector
+ * @param {string} params.strategy - Selector strategy: 'css', 'xpath', or 'text'
+ */
+(function(params) {
+   const { selector, strategy } = params;
+   let element;
+
+   if (strategy === 'text') {
+      // Find element containing text
+      const xpath = "//*[contains(text(), '" + selector + "')]";
+      const result = document.evaluate(
+         xpath,
+         document,
+         null,
+         XPathResult.FIRST_ORDERED_NODE_TYPE,
+         null
+      );
+      element = result.singleNodeValue;
+   } else if (strategy === 'xpath') {
+      // XPath selector
+      const result = document.evaluate(
+         selector,
+         document,
+         null,
+         XPathResult.FIRST_ORDERED_NODE_TYPE,
+         null
+      );
+      element = result.singleNodeValue;
+   } else {
+      // CSS selector (default)
+      element = document.querySelector(selector);
+   }
+
+   if (element) {
+      const outerHTML = element.outerHTML;
+      // Truncate long HTML to avoid overwhelming output
+      const truncated = outerHTML.length > 200
+         ? outerHTML.substring(0, 200) + '...'
+         : outerHTML;
+      return 'Found element: ' + truncated;
+   }
+
+   return 'Element not found';
+})

package/dist/driver/scripts/focus.js

@@ -0,0 +1,17 @@
+/**
+ * Focus an element
+ *
+ * @param {Object} params
+ * @param {string} params.selector - CSS selector for element to focus
+ */
+(function(params) {
+   const { selector } = params;
+
+   const element = document.querySelector(selector);
+   if (!element) {
+      throw new Error(`Element not found: ${selector}`);
+   }
+
+   element.focus();
+   return `Focused element: ${selector}`;
+})

package/dist/driver/scripts/get-styles.js

@@ -0,0 +1,41 @@
+/**
+ * Get computed CSS styles for elements
+ *
+ * @param {Object} params
+ * @param {string} params.selector - CSS selector for element(s)
+ * @param {string[]} params.properties - Specific CSS properties to retrieve
+ * @param {boolean} params.multiple - Whether to get styles for all matching elements
+ */
+(function(params) {
+   const { selector, properties, multiple } = params;
+
+   const elements = multiple
+      ? Array.from(document.querySelectorAll(selector))
+      : [document.querySelector(selector)];
+
+   if (!elements[0]) {
+      throw new Error(`Element not found: ${selector}`);
+   }
+
+   const results = elements.map(element => {
+      const styles = window.getComputedStyle(element);
+
+      if (properties.length > 0) {
+         const result = {};
+         properties.forEach(prop => {
+            result[prop] = styles.getPropertyValue(prop);
+         });
+         return result;
+      }
+
+      // Return all styles
+      const allStyles = {};
+      for (let i = 0; i < styles.length; i++) {
+         const prop = styles[i];
+         allStyles[prop] = styles.getPropertyValue(prop);
+      }
+      return allStyles;
+   });
+
+   return JSON.stringify(multiple ? results : results[0]);
+})